2. EL 9
  3. keyutils-libs-devel
  4. keyctl_watch_key(3)

Scroll to navigation

KEYCTL_GRANT_PERMISSION(3) Linux Key Management Calls KEYCTL_GRANT_PERMISSION(3)

NAME

keyctl_watch_key - Watch for changes to a key

SYNOPSIS

#include <keyutils.h>

long keyctl_watch_key(key_serial_t key,
                      int watch_queue_fd
                      int watch_id);

DESCRIPTION

keyctl_watch_key() sets or removes a watch on key.

watch_id specifies the ID for a watch that will be included in notification messages. It can be between 0 and 255 to add a key; it should be -1 to remove a key.

watch_queue_fd is a file descriptor attached to a watch_queue device instance. Multiple openings of a device provide separate instances. Each device instance can only have one watch on any particular key.

Notification Record

Key-specific notification messages that the kernel emits into the buffer have the following format:


struct key_notification {
	struct watch_notification watch;
	__u32	key_id;
	__u32	aux;
};

The watch.type field will be set to WATCH_TYPE_KEY_NOTIFY and the watch.subtype field will contain one of the following constants, indicating the event that occurred and the watch_id passed to keyctl_watch_key() will be placed in watch.info in the ID field. The following events are defined:

This indicates that a watched key got instantiated or negatively instantiated. key_id indicates the key that was instantiated and aux is unused.
This indicates that a watched key got updated or instantiated by update. key_id indicates the key that was updated and aux is unused.
This indicates that a key got linked into a watched keyring. key_id indicates the keyring that was modified aux indicates the key that was added.
This indicates that a key got unlinked from a watched keyring. key_id indicates the keyring that was modified aux indicates the key that was removed.
This indicates that a watched keyring got cleared. key_id indicates the keyring that was cleared and aux is unused.
This indicates that a watched key got revoked. key_id indicates the key that was revoked and aux is unused.
This indicates that a watched key got invalidated. key_id indicates the key that was invalidated and aux is unused.
This indicates that a watched key had its attributes (owner, group, permissions, timeout) modified. key_id indicates the key that was modified and aux is unused.

Removal Notification

When a watched key is garbage collected, all of its watches are automatically destroyed and a notification is delivered to each watcher. This will normally be an extended notification of the form:


struct watch_notification_removal {
	struct watch_notification watch;
	__u64	id;
};

The watch.type field will be set to WATCH_TYPE_META and the watch.subtype field will contain WATCH_META_REMOVAL_NOTIFICATION. If the extended notification is given, then the length will be 2 units, otherwise it will be 1 and only the header will be present.

The watch_id passed to keyctl_watch_key() will be placed in watch.info in the ID field.

If the extension is present, id will be set to the ID of the destroyed key.

RETURN VALUE

On success keyctl_watch_key() returns 0 . On error, the value -1 will be returned and errno will have been set to an appropriate error.

ERRORS

The specified key does not exist.
The specified key has expired.
The specified key has been revoked.
The named key exists, but does not grant view permission to the calling process.
The specified key already has a watch on it for that device instance (add only).
The specified key doesn't have a watch on it (removal only).

LINKING

This is a library function that can be found in libkeyutils. When linking, -lkeyutils should be specified to the linker.

SEE ALSO

keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7)

28 Aug 2019 Linux